/**
 * Licensed to the Apache Software Foundation (ASF) under one or more contributor license
 * agreements.  See the NOTICE file distributed with this work for additional information regarding
 * copyright ownership.  The ASF licenses this file to you under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with the License.  You may obtain
 * a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License
 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 * or implied. See the License for the specific language governing permissions and limitations under
 * the License.
 */

package org.apache.zookeeper.server;

import org.apache.zookeeper.KeeperException;
import org.apache.zookeeper.KeeperException.SessionExpiredException;
import org.apache.zookeeper.KeeperException.SessionMovedException;

import java.io.PrintWriter;

/**
 *
 * 这是zk服务端用于管理session的基础接口。单节点和leander的zk服务端使用相同的 SessionTracker。
 * This is the basic interface that ZooKeeperServer uses to track sessions.
 * The standalone and leader ZooKeeperServer use the same SessionTracker.
 *
 * todo: 对于Follower服务器使用的SessionTracker，具体是什么意思？
 * The FollowerZooKeeperServer uses a SessionTracker which is basically a simple
 * shell to track information to be forwarded to the leader.
 */
public interface SessionTracker {

    /**
     * 创建session
     * @param sessionTimeout session超时事件
     * @return
     */
    long createSession(int sessionTimeout);

    /**
     * 添加session
     * @param id sessionId
     * @param to session超时事件
     */
    void addSession(long id, int to);

    /**
     * 重新触发session（即：把session超时事件往后移）
     * @param sessionId
     * @param sessionTimeout
     * @return false if session is no longer active
     */
    boolean touchSession(long sessionId, int sessionTimeout);

    /**
     * 标记session在程序中正在关闭
     * @param sessionId
     */
    void setSessionClosing(long sessionId);

    /**
     * 关闭
     */
    void shutdown();

    /**
     * 移除session
     * @param sessionId
     */
    void removeSession(long sessionId);

    /**
     * 检查session
     *
     * @param sessionId
     * @param owner
     * @throws KeeperException.SessionExpiredException
     * @throws SessionMovedException
     */
    void checkSession(long sessionId, Object owner) throws KeeperException.SessionExpiredException, SessionMovedException;

    void setOwner(long id, Object owner) throws SessionExpiredException;

    /**
     * 使用文本方式导出session信息，为了测试
     * @param pwriter the output writer
     */
    void dumpSessions(PrintWriter pwriter);

    /**
     * session接口
     */
    interface Session {
        long getSessionId();

        int getTimeout();

        boolean isClosing();
    }

    /**
     * session过期处理器
     */
    interface SessionExpirer {
        void expire(Session session);

        long getServerId();
    }
}
